/**
 * 中文栈数据结构封装 (zh-stack.js)
 * 支持栈的基本操作、链式调用、迭代器
 * 中文方法命名 + JSDoc 参数提示
 */

class 栈 {
  /**
   * 构造函数 - 创建栈实例
   * @param {Array} [初始数据=[]] 初始栈元素数组
   */
  constructor(初始数据 = []) {
    this._数据 = [...初始数据];
  }

  /**
   * 获取栈数据数组的副本
   * @returns {Array} 栈数据的副本数组
   */
  取值() {
    return [...this._数据];
  }

  /**
   * 入栈操作
   * @param {any} 元素 要入栈的元素
   * @returns {栈} 返回this以支持链式调用
   */
  入栈(元素) {
    this._数据.push(元素);
    return this;
  }

  /**
   * 出栈操作
   * @returns {any} 栈顶元素
   */
  出栈() {
    return this._数据.pop();
  }

  /**
   * 查看栈顶元素但不移除
   * @returns {any} 栈顶元素
   */
  查看栈顶() {
    return this._数据[this._数据.length - 1];
  }

  /**
   * 获取栈的大小
   * @returns {number} 栈中元素数量
   */
  大小() {
    return this._数据.length;
  }

  /**
   * 判断栈是否为空
   * @returns {boolean} 是否为空
   */
  是否为空() {
    return this._数据.length === 0;
  }

  /**
   * 清空栈
   * @returns {栈} 返回this以支持链式调用
   */
  清空() {
    this._数据 = [];
    return this;
  }

  /**
   * 遍历栈中的所有元素
   * @param {Function} 回调 回调函数，接收元素、索引、栈实例三个参数
   * @returns {栈} 返回this以支持链式调用
   */
  遍历(回调) {
    for (let i = 0; i < this._数据.length; i++) {
      回调(this._数据[i], i, this);
    }
    return this;
  }

  /**
   * 反向遍历栈中的所有元素
   * @param {Function} 回调 回调函数，接收元素、索引、栈实例三个参数
   * @returns {栈} 返回this以支持链式调用
   */
  反向遍历(回调) {
    for (let i = this._数据.length - 1; i >= 0; i--) {
      回调(this._数据[i], i, this);
    }
    return this;
  }

  /**
   * 映射操作，返回新数组
   * @param {Function} 回调 映射函数
   * @returns {Array} 映射后的新数组
   */
  映射(回调) {
    return this._数据.map(回调);
  }

  /**
   * 过滤操作，返回新数组
   * @param {Function} 回调 过滤函数
   * @returns {Array} 过滤后的新数组
   */
  过滤(回调) {
    return this._数据.filter(回调);
  }

  /**
   * 归约操作，从左到右
   * @param {Function} 回调 归约函数
   * @param {any} [初始值] 初始累积值
   * @returns {any} 最终归约结果
   */
  归约(回调, 初始值) {
    return this._数据.reduce(回调, 初始值);
  }

  /**
   * 查找元素，返回第一个匹配的元素
   * @param {Function} 回调 判断函数
   * @returns {any} 找到的元素，如果没找到则返回undefined
   */
  查找(回调) {
    return this._数据.find(回调);
  }

  /**
   * 查找元素索引，返回第一个匹配的元素索引
   * @param {Function} 回调 判断函数
   * @returns {number} 找到的元素索引，如果没找到则返回-1
   */
  查找索引(回调) {
    return this._数据.findIndex(回调);
  }

  /**
   * 判断是否包含指定元素
   * @param {any} 元素 要检查的元素
   * @returns {boolean} 是否包含
   */
  包含(元素) {
    return this._数据.includes(元素);
  }

  /**
   * 判断是否所有元素都满足条件
   * @param {Function} 回调 判断函数
   * @returns {boolean} 是否所有元素都满足条件
   */
  所有满足(回调) {
    return this._数据.every(回调);
  }

  /**
   * 判断是否至少有一个元素满足条件
   * @param {Function} 回调 判断函数
   * @returns {boolean} 是否至少有一个元素满足条件
   */
  存在满足(回调) {
    return this._数据.some(回调);
  }

  /**
   * 复制栈实例
   * @returns {栈} 新的栈实例
   */
  复制() {
    return new 栈(this._数据);
  }

  /**
   * 转换为字符串
   * @returns {string} 字符串表示
   */
  转字符串() {
    return this._数据.toString();
  }

  /**
   * 转换为JSON字符串
   * @returns {string} JSON字符串
   */
  转JSON() {
    return JSON.stringify(this._数据);
  }

  /**
   * 从JSON字符串创建栈实例
   * @param {string} jsonString JSON字符串
   * @returns {栈} 新的栈实例
   */
  static 从JSON(jsonString) {
    try {
      const 数据 = JSON.parse(jsonString);
      return new 栈(数据);
    } catch (错误) {
      console.error('JSON解析错误:', 错误);
      return new 栈();
    }
  }

  /**
   * 创建新的栈实例
   * @param  {...any} 元素 要添加的元素
   * @returns {栈} 新的栈实例
   */
  static 创建(...元素) {
    return new 栈(元素);
  }

  /**
   * 迭代器实现
   * @returns {Iterator} 迭代器对象
   */
  [Symbol.iterator]() {
    let 索引 = 0;
    const 数据 = this._数据;
    return {
      next() {
        if (索引 < 数据.length) {
          return { value: 数据[索引++], done: false };
        } else {
          return { done: true };
        }
      }
    };
  }

  /**
   * 生成器方法，用于for...of循环
   * @yields {any} 栈中的每个元素
   */
  *生成器() {
    for (const 元素 of this._数据) {
      yield 元素;
    }
  }

  /**
   * 静态方法：检查括号是否匹配
   * @param {string} 表达式 包含括号的表达式字符串
   * @returns {boolean} 括号是否匹配
   */
  static 括号匹配(表达式) {
    const 栈实例 = new 栈();
    const 括号映射 = { ')': '(', ']': '[', '}': '{' };
    
    for (const 字符 of 表达式) {
      if (['(', '[', '{'].includes(字符)) {
        栈实例.入栈(字符);
      } else if ([')', ']', '}'].includes(字符)) {
        if (栈实例.是否为空() || 栈实例.出栈() !== 括号映射[字符]) {
          return false;
        }
      }
    }
    
    return 栈实例.是否为空();
  }
}

// 同时支持 ES 模块和 CommonJS 导出
try {
  // 浏览器环境导出
  if (typeof exports === 'undefined') {
    window.栈 = 栈;
  }
} catch (e) {}

// CommonJS 导出

  module.exports = {
    栈,
    default: 栈
  };
  module.exports.栈 = 栈;


// ES 模块导出
// export { 栈 };
// export default 栈;